/* -*-html-*- */
/*! \mainpage ccl - Customizable Configuration Library

<div class="qindex">
The current version of ccl is $(VERSION), released $(DATE)
</div>

\section section_introduction Introduction

ccl is the customizable configuration library, a collection of
functions for application programmers wishing to interface with
user-editable configuration files containing key/value pairs.

ccl is customizable because it allows the comment, key/value, and
string literal delimiters to be programatically specified at runtime.

ccl is designed to be simple and portable; it has a small interface
consisting of five functions and is written in ANSI/ISO C.  ccl uses
<a href="http://www.stanford.edu/~blp/avl/">avl's</a> implemenation
of binary search trees for backend storage.

\section section_download Download

ccl is available at <a
href="https://sbooth.org/files/">https://sbooth.org/files/</a>.

\section section_documentation Documentation

ccl is documented using <a href="http://www.doxygen.org">doxygen</a>.  

You can browse the library's contents by using the navigation bar at
the top of this page.  A good starting point is the <a
href="globals.html">globals</a> page.

\section section_example Example

An example is the best way to understand how ccl works.  A
configuration file named \c example.conf might contain:

\verbatim## Sample configuration file 
Desktop-Picture = /usr/images/earth.jpg 
Position = Centered 
"Background Color" = Black 
\endverbatim

The following  code demonstrates how to parse and access this file
using ccl:

\code
#include "ccl/ccl.h"

struct ccl_t            config;
const struct ccl_pair_t *iter;

/* Set configuration file details */
config.comment_char = '#';
config.sep_char = '=';
config.str_char = '"';

/* Parse the file */
ccl_parse(&config, "example.conf");

/* Iterate through all key/value pairs */
while((iter = ccl_iterate(&config)) != 0) {
  printf("(%s,%s)\n", iter->key, iter->value);
}

/* Clean up */
ccl_release(&config);
\endcode

When compiled, the snippet above produces the output

\verbatim(Background Color,Black)
(Desktop-Picture,/usr/images/earth.jpg)
(Position,Centered)
\endverbatim

\section section_bugs Reporting Bugs

If you think you have found a bug in ccl, then you should send as
complete a report as possible.  Ideally, you should include the text
you get by running \c config.guess and the text you see when you run
\c configure.

If you think you have tracked down the source of the bug, please
also send a patch made with diff -u5 which fixes the problem.

Please send bug reports, questions, comments and suggestions
to <a href="mailto:meATsboothDOTorg">Stephen F. Booth</a>.

\section section_license License

Copyright &copy; 2004 - 2005 <a href="mailto:meATsboothDOTorg">Stephen
F. Booth</a>.

Permission to use, copy, modify, and distribute this software and its
documentation under the terms of the GNU General Public License is
hereby granted. No representations are made about the suitability of
this software for any purpose. It is provided "as is" without express
or implied warranty. See the <a
href="http://www.gnu.org/copyleft/gpl.html">GNU General Public
License</a> for more details.

*/
